home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 41 / Amiga Format CD41 (1999-06)(Future Publishing)(GB)[!][issue 1999-07].iso / -seriously_amiga- / misc / amised / viewers / sources / viewerlib.doc < prev    next >
Text File  |  1999-04-19  |  14KB  |  459 lines
  1. TABLE OF CONTENTS
  2.  
  3. ViewerLib/--background--
  4. ViewerLib/BuiltRequester
  5. ViewerLib/CloseRequester
  6. ViewerLib/CursDown
  7. ViewerLib/CursLeft
  8. ViewerLib/CursRight
  9. ViewerLib/CursSOL
  10. ViewerLib/CursUp
  11. ViewerLib/DoRreturn
  12. ViewerLib/FileRequester
  13. ViewerLib/FreeRequester
  14. ViewerLib/GetWinPos
  15. ViewerLib/GetImage
  16. ViewerLib/GetYPos
  17. ViewerLib/InternalCommand
  18. ViewerLib/LoadImage
  19. ViewerLib/NewViewerbar
  20. ViewerLib/SetViewervar
  21. ViewerLib/SetViewervar2
  22. ViewerLib/ShowRequester
  23. ViewerLib/WordWrapSaveFilter
  24. ViewerLib/--background--                             ViewerLib/--background--
  25.  
  26.  This library is passed to all viewers of AMIS, it can not be opened the
  27. normal way. But for the rest it works just like a normal library (note that
  28. the base of this library is the AMIS_Base which is not a library structure).
  29.  
  30.  Viewers can use this library to control some parts of AMIS and to be able
  31. to use some standard functions AMIS has built-in, such as requesters, image
  32. loading (with cache and datatypes), etc.
  33.  
  34.  Every new version of AMIS will have more functions available for the
  35. viewers. Therefore you must set the version of AMIS which your viewer needs
  36. in the vw_version field of the Viewer structure.
  37.  
  38.    NOTE
  39.     At the moment this documentation is not fully completed, later
  40.     archives will have (more) complete documentation and better includes
  41.     too. If you want too create a new viewer you can send me an E-mail
  42.     (wmestrom@cs.ruu.nl) and I will send you the latest version of AMIS
  43.     with the autodocs and includes you need.
  44.  
  45. ViewerLib/BuiltRequester                             ViewerLib/BuiltRequester
  46.  
  47.    NAME
  48.     BuiltRequester -- Built a requester from a requester definition.
  49.               (V1.00)
  50.  
  51.    SYNOPSIS
  52.        reqbase = BuiltRequester(A0,A1)
  53.        D0
  54.  
  55.     struct ReqBase *BuiltRequester(struct Req *, struct TagItems *);
  56.  
  57.    FUNCTION
  58.     This function builts a ReqBase structure from a requester
  59.     definition. This ReqBase can then be used to display the requester
  60.     and close it again (and open it again, etc). When you are done with
  61.     the requester you can free this structure using the FreeRequester()
  62.     function.
  63.  
  64.    INPUTS
  65.     Req  -
  66.     Tags:
  67.         AM_Screen
  68.         This tag can be used to specify on which screen you want the
  69.         requester to appear. When this tag is ommited or zero the
  70.         default public screen will be used.
  71.  
  72.         AM_Locale
  73.         This tag can be used to pass a catalog which will be used to
  74.         localize the text in the requester (buttons, title, etc).
  75.  
  76.         AM_LocaleOffset
  77.         This indicates which offset should be added to the locale
  78.         string numbers given in the requester definition and gadgets
  79.         taglist.
  80.  
  81.         AM_MessagePort
  82.         Here you can pass a pointer to a message port which you want
  83.         to use as the IDCMP port for this requester. Here you will
  84.         receive commands like mouse clicks etc. If this tag is
  85.         ommited or zero a port will be created.
  86.  
  87.         AM_ESC_Function
  88.         Here you can pass a pointer to a function that you want to
  89.         be executed when the escape key is pressed.
  90.  
  91.         AM_Return_Button
  92.         Here you can pass a pointer to a function that you want to
  93.         be executed when the return key is pressed.
  94.  
  95.         AM_CloseFunction
  96.         Here you can pass a pointer to a function that you want to
  97.         be executed when the close button of the requester window is
  98.         selected.
  99.  
  100.         AM_Gadgets
  101.         The ti_data of this tag should be an other taglist. In this
  102.         taglist you can specify all text and buttons you want to be
  103.         displayed in the requester. These are the tags you can use
  104.         in this taglist:
  105.  
  106.             AM_SameWidth
  107.             The next n number of gadgets will all have the same
  108.             width. Where ti_data defines the value of n. The
  109.             width will be stored in the iw_groupwidth field of
  110.             the ReqBase structure for later use when these
  111.             gadgets are created.
  112.             AM_SameLeft
  113.             The next n number of gadgets will all have the same
  114.             x coordinate. Where ti_data defines the value of n.
  115.             The width will be stored in the iw_groupleft field
  116.             of the ReqBase structure for later use when these
  117.             gadgets are created.
  118.             AM_Code
  119.             Here you can specify a pointer to a function you
  120.             want to be executed while the gadgets are being
  121.             created. When this function is called all gadgets
  122.             defined earlier in the taglist are already created,
  123.             all gadgets later in the taglist are not. This
  124.             function can be used to change gadget definitions to
  125.             make the layout a little nicer. For example you can
  126.             use the width of some buttons created earlier to
  127.             calculate the width of one of the following gadgets.
  128.             This function may also change the iw_width,
  129.             iw_height, iw_groupwidth and iw_groupleft fields of
  130.             the ReqBase structure. (iw_width and iw_height are
  131.             the width and height of the requester, which are
  132.             initialy set to the values passed in the Req
  133.             structure).
  134.  
  135.             AM_Button
  136.             The ti_data field should be a pointer to a AR_Button
  137.             structure. This button gadget will be created and
  138.             added to the requester.
  139.             AM_CheckMark
  140.             The ti_data field should be a pointer to a
  141.             AR_CheckMark structure. This checkmark gadget will
  142.             be created and added to the requester.
  143.             AM_Cycle
  144.             The ti_data field should be a pointer to a AR_Cycle
  145.             structure. This cycle gadget will be created and
  146.             added to the requester.
  147.             AM_Listview
  148.             The ti_data field should be a pointer to a
  149.             AR_Listview structure. This listview gadget will be
  150.             created and added to the requester.
  151.             AM_Slider
  152.             The ti_data field should be a pointer to a AR_Slider
  153.             structure. This slider gadget will be created and
  154.             added to the requester.
  155.             AM_Integer
  156.             The ti_data field should be a pointer to a
  157.             AR_Integer structure. This integer gadget will be
  158.             created and added to the requester.
  159.             AM_Number
  160.             The ti_data field should be a pointer to a AR_Number
  161.             structure. This number gadget will be created and
  162.             added to the requester.
  163.             AM_String
  164.             The ti_data field should be a pointer to a AR_String
  165.             structure. This string gadget will be created and
  166.             added to the requester.
  167.             AM_Text
  168.             The ti_data field should be a pointer to a AR_Text
  169.             structure. This text gadget will be created and
  170.             added to the requester.
  171.  
  172.             AM_UserGadget
  173.             The ti_data field of this tag should be a pointer to
  174.             a normal intuition Gadget structure. This gadget
  175.             will be added to the requester.
  176.  
  177.             AM_BackBox
  178.             The ti_data field should be a pointer to a
  179.             AR_BackBox structure. This will created an image of
  180.             a normal requester background pattern, this image
  181.             will be added to the requester. (This is the same
  182.             pattern as used in the AMIS requesters). Note that
  183.             this should be the last item of your taglist since
  184.             all gadgets are rendered in reverse order as you
  185.             specify them in your list. (and normally a
  186.             background should be rendered first so all other
  187.             graphics will be drawn over the background).
  188.  
  189.             AM_IText
  190.             The ti_data field should be a pointer to a IntuiText
  191.             structure. This text will be printed in the
  192.             requester when it is opened using the intuition
  193.             PrintIText() function.
  194.  
  195.    NOTE
  196.     You will normally want to set the AM_MessagePort to the AMIS_MsgPort
  197.     passed to you in the AMIS_Structure. Because if you don't do this
  198.     the requester will not react to ANY user input(!), you will have to
  199.     handle all messages by yourself. If you do pass the AMIS_MsgPort as
  200.     the message port to be used, AMIS will handle all user input from
  201.     clicking on the windows close gadget to pressing a gadget shortkey.
  202.  
  203.    RESULT
  204.     reqbase    - A pointer to a ReqBase structure or zero when this
  205.           function failed (usually out of memory).
  206.  
  207.    SEE ALSO
  208.     CloseRequester(), FreeRequester(), ShowRequester()
  209.  
  210. ViewerLib/CloseRequester                             ViewerLib/CloseRequester
  211.  
  212.    NAME
  213.     CloseRequester -- Remove a requester from the screen (close the
  214.               window). (V1.00)
  215.  
  216.    SYNOPSIS
  217.        CloseRequester(A0)
  218.  
  219.     void CloseRequester(struct ReqBase *);
  220.  
  221.    FUNCTION
  222.     This function will close the requester window. The gadgets etc. are
  223.     not freed so you can open the window again using the ShowRequester()
  224.     function. You don't have to re-built the requester first.
  225.  
  226.    INPUT
  227.     ReqBase - The ReqBase structure BuiltRequester() passed to you.
  228.  
  229.    SEE ALSO
  230.     BuiltRequester(), FreeRequester(), ShowRequester()
  231.  
  232. ViewerLib/CursDown                                         ViewerLib/CursDown
  233.  
  234.    NAME
  235.     CursDown -- Move the cursor of the active window one line down.
  236.  
  237.    SYNOPIS
  238.     Err = CursDown()
  239.     D0
  240.  
  241.     ULONG CursDown(void);
  242.  
  243.    FUNCTION
  244.     This function will move the cursor of the active window one line
  245.     down. It will do nothing when the cursor was on the last line.
  246.  
  247.    RESULT
  248.     Err - Zero when everything went ok. 10 when there was no active
  249.           editor window.
  250.  
  251.    SEE ALSO
  252.     CursLeft(), CursRight(), CursSOL(), CursUp()
  253.  
  254. ViewerLib/CursLeft                                         ViewerLib/CursLeft
  255.  
  256.    NAME
  257.     CursLeft -- Move the cursor of the active window one character left.
  258.  
  259.    SYNOPIS
  260.     Err = CursLeft()
  261.     D0
  262.  
  263.     ULONG CursLeft(void);
  264.  
  265.    FUNCTION
  266.     This function will move the cursor of the active window one
  267.     character to the left. It will jump to the previous line when the
  268.     cursor was on the first character of the line.
  269.  
  270.    RESULT
  271.     Err - Zero when everything went ok. 10 when there was no active
  272.           editor window.
  273.  
  274.    SEE ALSO
  275.     CursDown(), CursRight(), CursSOL(), CursUp()
  276.  
  277. ViewerLib/CursRight                                       ViewerLib/CursRight
  278.  
  279.    NAME
  280.     CursRight -- Move the cursor of the active window one character
  281.              right.
  282.  
  283.    SYNOPIS
  284.     Err = CursRight()
  285.     D0
  286.  
  287.     ULONG CursRight(void);
  288.  
  289.    FUNCTION
  290.     This function will move the cursor of the active window one
  291.     character to the right. It will jump to the next line if the cursor
  292.     was on the last character of the line.
  293.  
  294.    RESULT
  295.     Err - Zero when everything went ok. 10 when there was no active
  296.           editor window.
  297.  
  298.    SEE ALSO
  299.     CursDown(), CursLeft(), CursSOL(), CursUp()
  300.  
  301. ViewerLib/CursSOL                                           ViewerLib/CursSOL
  302.  
  303.    NAME
  304.     CursSOL -- Move the cursor of the active window to the first
  305.            character of the line.
  306.  
  307.    SYNOPIS
  308.     Err = CursSOL()
  309.     D0
  310.  
  311.     ULONG CursSOL(void);
  312.  
  313.    FUNCTION
  314.     This function will move the cursor of the active window to the first
  315.     character of the line.
  316.  
  317.    RESULT
  318.     Err - Zero when everything went ok. 10 when there was no active
  319.           editor window.
  320.  
  321.    SEE ALSO
  322.     CursDown(), CursLeft(), CursRight(), CursUp()
  323.  
  324. ViewerLib/CursUp                                             ViewerLib/CursUp
  325.  
  326.    NAME
  327.     CursUp -- Move the cursor of the active window one line up.
  328.  
  329.    SYNOPIS
  330.     Err = CursUp()
  331.     D0
  332.  
  333.     ULONG CursUp(void);
  334.  
  335.    FUNCTION
  336.     This function will move the cursor of the active window one line up.
  337.     It will do nothing when the cursor is on the first line.
  338.  
  339.    RESULT
  340.     Err - Zero when everything went ok. 10 when there was no active
  341.           editor window.
  342.  
  343.    SEE ALSO
  344.     CursDown(), CursLeft(), CursRight(), CursSOL()
  345.  
  346. ViewerLib/DoReturn                                         ViewerLib/DoReturn
  347.  
  348.    NAME
  349.     DoReturn -- Insert a return in the active editor window.
  350.  
  351.    SYNOPIS
  352.     Err = DoReturn()
  353.     D0
  354.  
  355.     ULONG DoReturn(void);
  356.  
  357.    FUNCTION
  358.     This function will do exactly the same as what happens when the user
  359.     presses the [Return] key (if it wasn't redefined of course.
  360.  
  361.    RESULT
  362.     Err - Zero when everything went ok. 10 when there was no active
  363.           editor window.
  364.  
  365. ViewerLib/FreeRequester                               ViewerLib/FreeRequester
  366.  
  367.    NAME
  368.     FreeRequester -- Free all memory (gadgets etc.) used by a requester.
  369.              (V1.00)
  370.  
  371.    SYNOPSIS
  372.        FreeRequester(A0)
  373.  
  374.     void FreeRequester(struct ReqBase *);
  375.  
  376.    FUNCTION
  377.     This function will free all memory, gadgets, etc. used by a
  378.     requester. NOTE: The ReqBase structure will also be freed, so it is
  379.     invalid after you have called this function!
  380.  
  381.    INPUT
  382.     ReqBase - The ReqBase structure BuiltRequester() passed to you.
  383.  
  384.    SEE ALSO
  385.     BuiltRequester(), CloseRequester(), ShowRequester()
  386.  
  387. ViewerLib/GetImage                                         ViewerLib/GetImage
  388.  
  389.    NAME
  390.     GetImage -- load an image using datatypes (only available with
  391.             kickstart 3.0 or higher), if the image is already in the
  392.             cache it will not be loaded again.
  393.  
  394.    SYNOPSIS
  395.     object = GetImage(A1)
  396.     D0
  397.  
  398.     struct Object *GetImage(char *filename);
  399.  
  400.    FUNCTION
  401.     This function will check AMIS cache if this image is already loaded,
  402.     if it is not it will be loaded and added to the cache. Then a
  403.     pointer to a datatype object will be returned.
  404.  
  405.    INPUT
  406.     filename - the filename of the image you want to load, this function
  407.            also supports filenames in the format:
  408.            "file://localhost/...".
  409.            Filenames in the format:
  410.            "http://..." are completely ignored.
  411.  
  412.    RESULT
  413.     object - a pointer to a datatype object or zero if the file could
  414.          not be loaded.
  415.  
  416.    SEE ALSO
  417.     LoadImage()
  418.  
  419. ViewerLib/InternalCommand                           ViewerLib/InternalCommand
  420.  
  421.    NAME
  422.     InternalCommand -- Send AMIS an internal command.
  423.  
  424.    SYNOPIS
  425.     result = InternalCommand(A0)
  426.     D0
  427.  
  428.     ULONG InternalCommand(char *command);
  429.  
  430.    FUNCTION
  431.     With this function you can send AMIS an internal command which AMIS
  432.     will execute and return the result of that command to you. It works
  433.     with all internal commands which you can find in the AMIS.guide.
  434.  
  435.    RESULT
  436.     result - Result of the internal command.
  437.  
  438. ViewerLib/ShowRequester                               ViewerLib/ShowRequester
  439.  
  440.    NAME
  441.     ShowRequester -- Show a requester, built using the BuiltRequester()
  442.              function. (V1.00)
  443.  
  444.    SYNOPSIS
  445.        ShowRequester(A0)
  446.  
  447.     void ShowRequester(struct ReqBase *);
  448.  
  449.    FUNCTION
  450.     This function will show a requester built by the BuiltRequester
  451.     function.
  452.  
  453.    INPUT
  454.     ReqBase - The ReqBase structure BuiltRequester() passed to you.
  455.  
  456.    SEE ALSO
  457.     BuiltRequester(), CloseRequester(), FreeRequester()
  458.  
  459.